Sending Semantic Events (OD PG)

Inside Macintosh: OpenDoc Programmer's Guide / Part 2 - Programming: Chapter 9 - Semantic Events and Scripting

Sending Semantic Events
Although the ability to send semantic events is not required for scriptability, OpenDoc provides support for it. This section discusses the OpenDoc-specific aspects of sending semantic events; for more information, see the chapter "Creating and Sending Apple Events" in Inside Macintosh: Interapplication Communication.
The OpenDoc message interface object (ODMessageInterface) is responsible for constructing Apple events, getting and setting event attributes, parsing events, and sending events. This section describes how your part uses the message interface and the Apple Event Manager to send a semantic event.
To construct the Apple event, you call the CreateEvent method of the message interface object to create an ODAppleEvent object. You can then construct additional parameters and add them to the Apple event by calling the Apple Event Manager AEPutParamPtr or AEPutParamDesc function.

Constructing Object Specifiers
To send an Apple event to an OpenDoc part, the sender must use an object specifier that identifies the target part. The object specifier is typically in the direct parameter of the Apple event, although for events without direct parameters, OpenDoc places it in a subject attribute.
Conventional applications using the Apple Event Manager to send events to a part in an OpenDoc document construct the appropriate object specifier themselves. If your part sends a semantic event, you can use the methods described in this section to construct an object specifier. If you send a semantic event to your own part (as when recording), you follow the same procedures as when sending an event to another part.

Using CreatePartObjSpec
If your part sends a semantic event to another part, you can use the CreatePartObjSpec method of the message interface to construct an object specifier for the direct parameter of the event. You must also call the CreatePartAddrDesc method of the message interface to create an address descriptor that identifies the process (OpenDoc document) in which the destination part resides.
If you use CreatePartObjSpec, OpenDoc dispatches to the specified part directly, without calling the Resolve method of the name resolver. This dispatching is efficient and fast. However, you cannot inspect the contents of the object specifier constructed by CreatePartObjSpec or use it for recording, and you cannot use it as a component of another object specifier that you construct.

Using EmbeddedFrameSpec
You can also use the EmbeddedFrameSpec method of ODPart to help construct an object specifier. You can inspect the resulting specifier, you can use it for recording, and you can use it as the direct parameter or as another parameter in an Apple event. Object specifiers created through EmbeddedFrameSpec have forms such as "embedded frame 2 of embedded frame 1 of the root frame".
To construct an object specifier in this way, you call the EmbeddedFrameSpec method of the part containing the frame that is the target for the event. Here is the interface to EmbeddedFrameSpec:
void EmbeddedFrameSpec(in ODFrame embeddedFrame, 
                       in ODObjectSpec spec);
A part receiving this method call should first call the EmbeddedFrameSpec method of its own containing part. It should then create an object specifier for the supplied embedded frame (using index number or any other appropriate identifying characteristic) and add it to the return value from its own call to EmbeddedFrameSpec. The final object specifier returned to the original caller thus describes the target frame in the context of its document.
A root part receiving this call should return a null object specifier.
Constructing object specifiers with EmbeddedFrameSpec is most useful for situations in which a target part's position in the embedding hierarchy is more important than its specific identity. However, EmbeddedFrameSpec fails if any part in the embedding hierarchy from the target frame to the root frame is not scriptable or has not implemented the EmbeddedFrameSpec method. Also, an object specifier constructed by this method becomes incorrect if the identifying characteristic of any frame in the hierarchy changes.

Using Persistent Object ID
The most reliable method for constructing an object specifier for a part is by using its persistent object ID. Use the persistent ID if you are constructing an object specifier and your call to EmbeddedFrameSpec fails, if you are sending an Apple event to a part with no display frames, or any time you need an object specifier that will be valid for a part regardless of its position in the embedding hierarchy.
Call the GetPersistentObjectID method of the target frame's or part's draft and use the return value in the object specifier. If your own frame is the target, as when recording, call your own draft's GetPersistentObjectID method and pass it your own display frame.

Sending the Event
To send the Apple event, you call the Send method of the message interface object. The message interface adds a subject attribute representing the target part (your part if you are sending the event to yourself) to the event. The message interface also generates and keeps track of the return ID for the event so that the reply can be routed back to your part editor's reply event handler.